Queries

Use Orbital's Investigate page to construct and run queries across identified endpoints to gather system information.

  1. In the Endpoints field, enter the ID of one or more endpoints in your organization that will be queried for information.

To remove an endpoint from the field, click the X at the right end of the endpoint label.

  1. You can add multiple random endpoints. Click at the right end of the field. The Add Random Endpoints dialog opens.

    2. Note: The default value for the Endpoints field is 10, it is not the maximum number of endpoints you can include in a query. This value can be changed by either typing in a new number into the field or using the up and down arrows to specify another number.

  2. Type the number of random endpoints you wish to run the query against into the Number field, if you wish to include more or less than ten endpoints.

  3. Click Add. The endpoints are then added to the Endpoints field.

SQL - Enter a Query

You can enter or paste a SELECT statement in the SQL field, or select one from the Query Catalog.

  1. Click Browse Query Catalog. The Query Catalog dialog opens.

    2. The catalog contains a collection of pre-defined queries that have been created by the Orbital engineering team and TRE (Threat Research for Endpoint) to help you get started. This information should help you quickly learn the power of Orbital and osquery for threat hunting.

    A Search field appears at the top of the dialog. The query list will automatically adjust to display only those catalog queries that contain the search term(s).

  2. Click on a query name to view detailed information:

  3. Choose a query from the list. This will display the selected query details in the Catalog dialog.

The query detail dialog includes a detailed query description, plus the ID, OS, Categories, ATT&CK™ Techniques and Tactics, information and warning messages, and the SQL SELECT statement. You can copy the SQL by clicking the clipboard icon, or click the + icon to add the SQL statement to your query.

Note: Some catalog queries will require additional parameters once they have been added. These queries, shown in the figure below, will display one or more Parameters fields describing the required information after they've been added.
Note: The SQL statements of queries added from the Catalog will be hidden by default. To display the SQL, click on the name of the catalog query.

Other useful cataloged queries to start with include:

  • Inventory System Information

  • Process Mutex Search

  • SHA-256 Hash of Running Processes

  • Logged In Users

Note: Any values or parameters you enter into the Investigate page fields will be retained if you move to another page or tab, then return to the Investigate page. However, if you click Clear, refresh your browser, or your Orbital session expires, any values entered into the Investigate page fields will not be retained.

Running an Organization Query From the Catalog

Follow the steps below to run an organization query:

  1. Click Investigate to open the Investigate page.

  2. Define the endpoints that the query will be run against.

    1. Enter the ID for one or more of your organization's endpoints in the Endpoints field.

    or

    1. Click the button located under the lower-right corner of the Endpoints field to add multiple random endpoints. The Add Random Endpoints dialog opens.

    2. Select the desired operating system or system(s) from the Add Random Endpoints dialog.

    3. Click Add. The selected endpoints are added to the Endpoints field.

  3. Define your query by selecting an existing query from the Orbital Catalog.

    1. Click Browse Query Catalog. The Query Catalog popup window opens.

    2. Type the name of the query you wish to run in the Search field. The query list will automatically adjust to only include the catalog queries that contain the search term(s).

    3. Click on the desired query name to view its detailed information.

      4. Review the contents of the query's detailed information and decide if you wish to use the query or not.

      • If you decide not to use the query, click the Back button located in the top-left of the page to return to the query search list.

    4. When you have found the query you wish to run, click Add to Query.

    5. Add any required parameters in the Parameters field if the query requires you to specify them.

  4. Click Run Query to run the query and view the results. The results will be returned in the right-side pane.

Saving A Query To the Catalog

To save a custom query to the Orbital catalog:

  1. Navigate to the Query page.

  2. Place your cursor in the Custom SQL field.

  3. Type your SQL statement into the Custom SQL field. You will notice that as you type your SQL statement, the Save Query button is displayed.

    • If you need to type a multi-statement query, click the plus located at the right end of the **Custom SQL** field.

    This will clear the Custom SQL field and place the previous SQL statement at the bottom of the page.

  4. Click Save Query. This will display the Save Query dialog.

  5. Type the name that the query will be saved under in the catalog in the Query Name field.

  6. Type a description of the query into the Description field.

  7. Select the operating system or operating systems that the query will be run against, using the OS checkboxes. This defaults to no operating systems selected. Once you have selected one or more operating systems, the Save button will be displayed.

  8. Click Save. This will remove the Save Query dialog from the screen and return to the Query page. The newly saved query is listed at the bottom of the page.

More Info